home *** CD-ROM | disk | FTP | other *** search
/ Disc to the Future 2 / Disc to the Future Part II Programmer's Reference (Wayzata Technology)(6013)(1992).bin / MAC / THINKC / 5 / CRON_1 / STANDARD / BUFFERMG.H next >
Text File  |  1991-09-01  |  8KB  |  248 lines
  1. #ifndef _BufferMgr_
  2. #define _BufferMgr_
  3.  
  4.  
  5. #ifndef NULL
  6. #define NULL            0L
  7. #endif
  8.  
  9.  
  10. typedef enum {
  11.     BufferMemDflt = 0,    //    Allocate in current heap zone only.
  12.     BufferMemTemp,        //    Allocate in System 7 temporary memory space only.
  13.     BufferMemDfltTemp,    //    Try BufferMemDflt mode first, then BufferMemTemp mode.
  14.     BufferMemTempDflt    //    Try BufferMemTemp mode first, then BufferMemDftl mode.
  15. } BufferAllocMethods;
  16.  
  17.  
  18. Handle                    BufferCreate(long InitialSize, long ExpansionFactor, BufferAllocMethods AllocMethod);
  19. void                    BufferDispose(Handle Buffer);
  20.  
  21. Ptr                        BufferOpen(Handle Buffer);
  22. void                    BufferClose(Handle Buffer);
  23.  
  24. void                    BufferClear(Handle Buffer);
  25. void                    BufferCompact(Handle Buffer);
  26.  
  27. Ptr                        BufferAdd(Handle Buffer, long DataSize, Ptr DataPtr);
  28. void                    BufferDel(Handle Buffer, long DataSize);
  29.  
  30. Ptr                        BufferPtrGet(Handle Buffer);
  31. Ptr                        BufferInfoGet(Handle Buffer, long *DataSize, long *ElementCount);
  32.  
  33.  
  34. /*    ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  35.     Buffer Manager -- Procedure Summary
  36.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  37.     
  38.     
  39.     The Buffer Manager is a set of routines which take a lot of the 
  40.     work out of maintiaing a growing block of relocatable memory. It 
  41.     automatically handles expanding the block of memory to accomodate
  42.     any data you add to it, and helps make the process as efficient 
  43.     as possible by automatically preallocating storage for the block.
  44.     
  45.     The Buffer Manager doesn't do anything you couldn't do yourself
  46.     with Memory Manager routines, of course -- it just saves you all
  47.     that trouble.
  48.     
  49.     
  50.     Creating and Disposing of Buffers
  51.     Ñ    BufferCreate
  52.     Ñ    BufferDispose
  53.     
  54.     Accessing Data in Buffers
  55.     Ñ    BufferOpen
  56.     Ñ    BufferClose
  57.     
  58.     Cleaning-Up Buffers
  59.     Ñ    BufferClear
  60.     Ñ    BufferCompact
  61.     
  62.     Adding and Deleting Data to/from Buffers
  63.     Ñ    BufferAdd
  64.     Ñ    BufferDel
  65.     
  66.     Information on Buffers
  67.     Ñ    BufferPtrGet
  68.     Ñ    BufferInfoGet
  69.     
  70.     
  71.     
  72.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  73.     Creating and Disposing of Buffers
  74.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  75.     
  76.     
  77.     BufferCreate
  78.     ╤╤╤╤╤╤╤╤╤╤╤╤
  79.     
  80.     Handle BufferCreate(long InitialSize, long ExpansionFactor, 
  81.         BufferAllocMethods AllocMethod);
  82.     
  83.     BufferCreate creates a new buffer with InitialSize bytes immed-
  84.     iately reserved for its use.  The buffer will be allocated in the
  85.     manner specified by the AllocMethod parameter.  The function returns 
  86.     a handle to the buffer, or NULL if the buffer could not be created.  
  87.     Any time the buffer becomes full, it will automatically grow by a 
  88.     minimum of ExpansionFactor bytes.
  89.     
  90.     WARNING:  Do not attemp to specify the BufferMemTemp, BufferMemTempDflt,
  91.               or BufferMemDfltTemp modes in the AllocMethod parameter 
  92.               unless you have already verified that support for real, 
  93.               tracked temporary memory is available.  This support exists 
  94.               in System 7, but not in previous systems.  The Gestalt 
  95.               function should be used to check for the availability of 
  96.               these features.  See IM VI pg. 28-37, 28-41.
  97.     
  98.     
  99.     BufferDispose
  100.     ╤╤╤╤╤╤╤╤╤╤╤╤╤
  101.     
  102.     void BufferDispose(Handle Buffer);
  103.     
  104.     BufferDispose disposes of all memory associated with the buffer 
  105.     specified by the Buffer parameter.
  106.     
  107.     
  108.     
  109.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  110.     Accessing Data in Buffers
  111.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  112.     
  113.     
  114.     BufferOpen
  115.     ╤╤╤╤╤╤╤╤╤╤
  116.     
  117.     Ptr BufferOpen(Handle Buffer);
  118.     
  119.     BufferOpen locks the buffer in memory and returns a pointer to 
  120.     beginning of your data in the buffer.  Try not to keep the buffer
  121.     open longer than necessary since it might interfere with calls to 
  122.     BufferAdd.
  123.     
  124.     
  125.     BufferClose
  126.     ╤╤╤╤╤╤╤╤╤╤╤
  127.     
  128.     void BufferClose(Handle Buffer);
  129.     
  130.     BufferClose unlocks the buffer in memory IF there are no outstand-
  131.     ing calls to BufferOpen.  Pointers to data in the buffer may become 
  132.     invalid at any time following the final BufferClose call.
  133.     
  134.     Note that BufferClose will only unlock the buffer when the number 
  135.     of calls made to BufferOpen is equal to the number of calls made
  136.     to BufferClose.  This prevents one procedure that was accessing data
  137.     in the buffer from inadvertantly unlocking the buffer while another
  138.     procedure is still trying to access data in the same buffer.
  139.     
  140.     
  141.     
  142.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  143.     Accessing Data in Buffers
  144.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  145.     
  146.     
  147.     BufferClear
  148.     ╤╤╤╤╤╤╤╤╤╤╤
  149.     
  150.     void BufferClear(Handle Buffer);
  151.     
  152.     BufferClear clears the specified buffer.  The buffer's physical size 
  153.     is left unchanged, but both the logical size and element count are 
  154.     set to zero.  Use this routine when you want to retain the buffer for 
  155.     future use, but you don't want to retain any of the data in it.  If, 
  156.     after calling BufferClear, you want to reclaim the memory formerly 
  157.     occupied by the data in the buffer, call BufferCompact.
  158.     
  159.             
  160.     BufferCompact
  161.     ╤╤╤╤╤╤╤╤╤╤╤╤╤
  162.     
  163.     void BufferCompact(Handle Buffer);
  164.     
  165.     BufferCompact compacts the specified buffer, reducing it's physical 
  166.     size to match it's logical size as closely as possible.  No data is 
  167.     lost from the buffer.
  168.     
  169.     
  170.     
  171.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  172.     Adding and Deleting Data to/from Buffers
  173.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  174.     
  175.     
  176.     BufferAdd
  177.     ╤╤╤╤╤╤╤╤╤
  178.     
  179.     Ptr BufferAdd(Handle Buffer, long DataSize, Ptr DataPtr);
  180.     
  181.     BufferAdd expands the specified buffer to accomodate DataSize add-
  182.     itional bytes, then uses BlockMove to copy DataSize bytes from the 
  183.     location pointed to by DataPtr to the end of the buffer, if DataPtr 
  184.     is not NULL.  BufferAdd returns a pointer to the start of the data 
  185.     copied into the buffer.  If the buffer could not be expanded, the 
  186.     pointer returned is NULL.  Note that the pointer returned is not 
  187.     guaranteed to remain valid unless the BufferOpen call has been used
  188.     to lock the buffer in memory.  Calling BufferOpen immediately after
  189.     calling BufferAdd IS legal.
  190.     
  191.     
  192.     BufferDel
  193.     ╤╤╤╤╤╤╤╤╤
  194.     
  195.     void BufferDel(Handle Buffer, long DataSize);
  196.     
  197.     BufferDel deletes DataSize bytes from the end of the buffer.
  198.     
  199.     
  200.     
  201.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  202.     Adding and Deleting Data to/from Buffers
  203.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  204.     
  205.     
  206.     BufferPtrGet
  207.     ╤╤╤╤╤╤╤╤╤╤╤╤
  208.     
  209.     Ptr BufferPtrGet(Handle Buffer);
  210.     
  211.     BufferPtrGet returns a pointer to the beginning of the data in the 
  212.     buffer.  Note that the buffer is not guaranteed to be locked in mem-
  213.     ory, so the pointer returned may not remain valid after calls that 
  214.     can move or purge memory.  In general, it's best to use BufferOpen 
  215.     since it CAN guarantee that the pointer will remain valid until the 
  216.     next call to BufferClose.
  217.     
  218.     
  219.     BufferInfoGet
  220.     ╤╤╤╤╤╤╤╤╤╤╤╤╤
  221.     
  222.     Ptr BufferInfoGet(Handle Buffer, long *DataSize, long *ElementCount);
  223.  
  224.     BufferInfoGet returns a pointer to the beginning of the data in the 
  225.     buffer, in exactly the same manner (and with the same limitations) as 
  226.     BufferPtrGet.  In DataSize it returns the total number of bytes occu-
  227.     pied by your data in the buffer.  In ElementCount it returns the num-
  228.     ber of elements in the buffer.  A buffer's ElementCount is incremented 
  229.     each time BufferAdd is called and decremented each time BufferDel is 
  230.     used.
  231.     
  232.     
  233.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  234.     Internet:    chrisj@emx.utexas.edu
  235.     UUCP:        {husc6|uunet}!cs.utexas.edu!ut-emx!chrisj
  236.     BitNet:        chrisj@utxvm.bitnet
  237.     AppleLink:    chrisj@emx.utexas.edu@internet#
  238.     CompuServe:    >INTERNET:chrisj@emx.utexas.edu
  239.     US Mail:    Chris Johnson, 3311 Red River #305, Austin, TX 78705
  240.     ╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤
  241. */
  242.  
  243.  
  244. #endif
  245.  
  246.  
  247.  
  248.